feat(): 实现 SubAgent WorkerRuntime 与角色策略（#274） by Cai-Tang-www · Pull Request #295 · 1024XEngineer/neo-code

Cai-Tang-www · 2026-04-14T15:39:44Z

背景

实现 #274：引入可复用的 SubAgent WorkerRuntime 内核，建立角色策略模型，并完成 Runtime 侧工厂注册与执行入口。

本 PR 不改动现有主会话单代理 Run 主链路，仅新增可独立调用的子代理能力。

本次改动

1) 新增 `internal/subagent` 核心模块

定义领域模型与接口：Role、Task、Budget、Capability、Output、WorkerRuntime、Factory
新增 RolePolicy 与默认角色策略：researcher / coder / reviewer
新增 WorkerRuntime 默认实现：Start / Step / Stop / Result / State / Policy
新增默认引擎与工厂实现：defaultEngine + WorkerFactory
新增输出契约校验：required sections + summary 必填

2) Runtime 接入

Service 增加 subAgentFactory 字段与默认注入
新增工厂注册方法：SetSubAgentFactory、SubAgentFactory
新增独立执行入口：RunSubAgentTask
新增子代理生命周期事件：
- subagent_started
- subagent_progress
- subagent_completed
- subagent_failed
- subagent_canceled

3) 测试

internal/subagent：角色策略、生命周期、错误分支、输出契约
internal/runtime：工厂注册与 RunSubAgentTask 事件流
全量测试通过：go test ./... -count=1

设计边界

仅实现 feat(subagent): 引入 WorkerRuntime 抽象与角色策略（researcher/coder/reviewer） #274 范围：WorkerRuntime 抽象、角色策略、生命周期、runtime 装配入口
不包含 feat(subagent): 实现 Task DAG 调度器（依赖、并发、预算、重试） #275（调度器）与 feat(subagent): 接入 CapabilityToken 与继承式权限隔离 #276（CapabilityToken 权限模型）

Closes #274
Refs #273

codecov · 2026-04-14T15:41:19Z

Codecov Report

❌ Patch coverage is 83.57934% with 89 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/runtime/subagent_run.go	74.57%	24 Missing and 6 partials ⚠️
internal/subagent/worker.go	85.57%	21 Missing and 8 partials ⚠️
internal/runtime/subagent_factory.go	65.95%	10 Missing and 6 partials ⚠️
internal/subagent/types.go	82.22%	4 Missing and 4 partials ⚠️
internal/subagent/output_contract.go	94.11%	2 Missing ⚠️
internal/subagent/policy.go	95.83%	1 Missing and 1 partial ⚠️
internal/subagent/util.go	88.23%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

Cai-Tang-www · 2026-04-14T15:51:52Z

/code 解决你说的review，帮我解决冲突，然后补齐测试率

fennoai · 2026-04-14T15:51:59Z

结果

已按你这条指令完成：处理 review 冲突点、补测试并推送到当前 PR 分支 feat(subagent)。

已完成内容

修复 review 提到的核心问题

internal/runtime/subagent_run.go
- 将 context.Canceled / context.DeadlineExceeded 分流为取消语义，终态事件改为 subagent_canceled，并保证 Result.StopReason 与事件一致。
- subagent_progress 改为非阻塞发射，避免慢消费者反压执行路径。
internal/subagent/worker.go
- Start 阶段新增 capability 与 policy.AllowedTools 的 fail-closed 约束（越权工具直接报错；未指定工具时回落到策略允许集）。
- Step 在引擎返回上下文取消错误时映射为 StateCanceled / StopReasonCanceled。
- StepInput.Trace 改为仅复制最近窗口，避免每步全量拷贝导致复杂度放大。
internal/subagent/output_contract.go
- RequiredSections 从“仅校验 summary”修正为“所有声明 required 的 section 均需有内容”。
- 抽出 section 名称归一化与合法性校验，供策略校验复用。
internal/subagent/policy.go
- RolePolicy.Validate 调整为只校验 required section 名称合法性（避免把内容校验提前到策略定义阶段）。

补齐测试

新增：
- internal/subagent/engine_test.go
- internal/subagent/output_contract_test.go
扩展：
- internal/subagent/worker_test.go
- internal/runtime/subagent_run_test.go
- internal/runtime/subagent_factory_test.go
新增覆盖点包括：取消态事件流、start 阶段 capability 越权失败、输出契约各 required section 校验、trace 窗口限制、nil/边界分支等。

验证

已执行：go test ./... -count=1（通过）
覆盖率关键结果（局部）：
- internal/subagent/engine.go 100%
- internal/runtime/subagent_factory.go 100%
- internal/runtime/subagent/subagent_run 与 internal/subagent/worker 相关分支覆盖已明显提升

提交信息

Commit: 9384e80
已推送到：Cai-Tang-www/neo-code 分支 feat(subagent)（即当前 PR head）

未执行项

未执行额外 CI 平台侧操作（如手动触发外部流水线）；仅完成本地构建/测试与代码推送。

View job run

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

Cai-Tang-www · 2026-04-14T16:13:39Z

@xgopilot 解决当前合并冲突点

fennoai · 2026-04-14T16:13:46Z

处理结果

已完成“解决当前合并冲突点”，并已推送到当前 PR 分支 feat(subagent)。

已完成内容

识别并处理与 origin/main 的冲突根因文件：
- internal/runtime/events.go
- internal/runtime/runtime.go
将 events.go 对齐到 main 的事件 envelope 结构，并新增兼容层文件：
- internal/runtime/events_subagent.go（保留 subagent 生命周期事件与旧事件名兼容常量）
引入 internal/runtime/controlplane（与 main 对齐）以承载事件负载类型依赖。
将 defaultMaxLoops 拆分到 internal/runtime/runtime_limits.go，减少与 runtime.go 主干冲突。
重构 subagent_factory 存储方式，避免在 Service 结构体上持续冲突：
- internal/runtime/subagent_factory.go
- internal/runtime/subagent_factory_test.go

验证结果

本地测试通过：go test ./... -count=1
三方合并验证通过：git merge-tree --write-tree --name-only --messages origin/main HEAD（无冲突）
GitHub PR 状态已恢复：
- mergeStateStatus: CLEAN
- mergeable: MERGEABLE

提交与推送

已推送提交：
- cc74bd4
- 730a61b
- a5bf778
远端分支：Cai-Tang-www/neo-code:feat(subagent)

未执行项

未执行额外的 CI 平台外操作（如手工触发外部流水线），仅完成代码修复、测试与推送。

View job run

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

wynxing · 2026-04-15T00:58:50Z

/review

Cai-Tang-www · 2026-04-15T01:29:55Z

/code 修复review

fennoai · 2026-04-15T01:30:08Z

处理结果

已按“修复review”完成代码修复并推送到当前 PR 分支 feat(subagent)。

已完成项

修复 subagent_factory 生命周期泄漏风险

文件：internal/runtime/subagent_factory.go、internal/runtime/runtime.go
调整为 Service 实例字段持有 subAgentFactory，移除全局 sync.Map[*Service]。
新增读写锁保护并在 NewWithFactory 注入默认工厂，避免全局强引用导致的 GC 泄漏风险。

修复默认引擎输出契约不一致

文件：internal/subagent/engine.go
默认引擎完成态输出补齐 summary/findings/patches/risks/next_actions/artifacts，与默认角色策略 required sections 对齐。

补充测试覆盖

文件：internal/runtime/subagent_factory_test.go
- 新增 TestServiceSubAgentFactoryIsolationAcrossInstances，验证工厂按实例隔离。
文件：internal/subagent/engine_test.go
- 新增默认引擎 required sections 非空校验。
- 新增默认引擎输出满足三种默认角色策略契约校验。

验证

已执行：go test ./... -count=1（通过）

提交与推送

Commit: e43f70c
Push: Cai-Tang-www/neo-code:feat(subagent)

未执行项

未执行 GitHub 平台侧 CI 操作（仅完成本地测试与推送）。

View job run

…t output contract Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

Cai-Tang-www · 2026-04-15T02:35:28Z

@xgopilot 解决冲突

fennoai · 2026-04-15T02:35:34Z

处理结果

已完成本次“解决冲突”，并已把修复推送到当前 PR 分支 feat(subagent)。

已完成内容

对齐 main 的 runtime 拆分结构，消除 internal/runtime/runtime.go 结构冲突来源：
- 新增并对齐：internal/runtime/event_emitter.go、internal/runtime/session_scheduler.go
- runtime.go 回归与 main 同构（保留本 PR 所需能力通过其它文件承载）
调整 subagent 工厂持有方式，避免依赖 Service 结构体字段导致的冲突热点：
- 更新 internal/runtime/subagent_factory.go
对齐 state 与事件 envelope 依赖，修复受影响调用与测试：
- 更新 internal/runtime/state.go
- 更新 internal/runtime/run.go
- 更新 internal/runtime/session_mutation.go
- 更新 internal/runtime/runtime_test.go
- 对齐 internal/runtime/runtime_internal_helpers_test.go 到 main，消除测试文件冲突

验证

go test ./... -count=1 通过
git merge-tree --write-tree --name-only --messages origin/main HEAD 无冲突（exit code 0）

提交与推送

新增提交：
- 062846d
- 631d8ab
- 1afecba
已推送到：Cai-Tang-www/neo-code:feat(subagent)

未执行项

未执行平台侧 CI/CD 人工操作（仅完成本地测试与冲突校验）。

View job run

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

phantom5099 · 2026-04-15T03:03:51Z

/review

fennoai

Focused review on runtime/subagent integration. I found a few correctness and safety gaps worth addressing before merge.

fennoai · 2026-04-15T03:08:17Z

+		Error:  errorText(stepErr),
+	}
+	select {
+	case s.events <- RuntimeEvent{


emitSubAgentProgress writes directly to s.events with a partially-filled RuntimeEvent, so envelope metadata (Timestamp, PayloadVersion, and run-scoped fields like Turn/Phase) stays zero-value for progress events. Since this PR introduces a richer event envelope, this creates inconsistent event contracts across event types. Please route this through the same envelope path (emitWithEnvelope / run-scoped emitter) so metadata is consistently populated.

fennoai · 2026-04-15T03:08:17Z

+		if result.State == subagent.StateSucceeded {
+			return result, nil
+		}
+		return result, errors.New(result.Error)


return result, errors.New(result.Error) can return an empty-string error when result.Error is blank (possible for custom WorkerRuntime implementations). Please add a fallback error message that includes at least state/stop_reason to keep failures diagnosable.

fennoai · 2026-04-15T03:08:18Z

+	w.stepCount++
+	delta := strings.TrimSpace(stepOutput.Delta)
+	if delta != "" {
+		w.trace = append(w.trace, delta)


w.trace appends every step but only the last traceWindowSize entries are ever consumed (cloneRecentTrace). With larger MaxSteps, this grows memory and allocation cost unnecessarily in the hot loop. Consider trimming in place (or using a ring buffer) when appending, so internal trace storage remains bounded.

fennoai · 2026-04-15T03:08:18Z

+	}, nil
+}
+
+// bindCapabilityToPolicy 将 capability 约束在角色策略允许的工具集合内。


Capability.AllowedPaths is accepted and normalized, but never enforced in Start/bindCapabilityToPolicy (only tools are filtered). This creates a policy gap: callers can provide path boundaries that are silently ignored. Either enforce path constraints here (or at the engine boundary) or remove the field until it is enforced to avoid a false sense of confinement.

Cai-Tang-www · 2026-04-15T03:22:51Z

/code 修复review

fennoai · 2026-04-15T03:22:58Z

处理结果

已按“修复review”完成修复并推送到当前 PR 分支 feat(subagent)。

已完成内容

修复 subagent_progress 事件 envelope 不一致

文件：internal/runtime/subagent_run.go
调整为进度事件也写入完整 envelope 元数据（Timestamp、PayloadVersion、Turn），同时保持非阻塞投递。

修复子代理终态空错误文本问题

文件：internal/runtime/subagent_run.go
新增 subAgentResultError 兜底：当 result.Error 为空时，返回包含 state 和 stop_reason 的可诊断错误。

修复 trace 热路径内存增长问题

文件：internal/subagent/worker.go
新增有界追加逻辑 appendTraceBounded，在每次追加 delta 时将内部 trace 存储限制在 traceWindowSize。

修复 Capability.AllowedPaths 被静默忽略问题

文件：internal/subagent/worker.go
在 bindCapabilityToPolicy 中改为 fail-closed：若传入 AllowedPaths，立即返回错误，避免产生“已受限”假象。

补充/更新测试

文件：internal/runtime/subagent_run_test.go
- 校验 subagent_progress 事件包含 envelope 元数据。
- 新增自定义 worker 失败且空错误文本时的 fallback 错误断言。
文件：internal/subagent/worker_test.go
- 新增 AllowedPaths fail-closed 测试。
- 新增 trace 内部存储上限测试。

验证结果

go test ./internal/runtime -run TestServiceRunSubAgentTask -count=1 通过
go test ./internal/subagent -run 'TestWorker(StartCapabilityPolicyGuard|TraceStorageBounded|TraceWindow)' -count=1 通过
go test ./... -count=1 通过

提交与推送

Commit: 727ed3f
Push: Cai-Tang-www/neo-code:feat(subagent)

未执行项

未执行平台侧 CI/CD 人工操作（仅完成本地测试与代码推送）。

View job run

…y bounds Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

feat(): 实现 SubAgent WorkerRuntime、角色策略与 Runtime 生命周期接入

2573fd1

This comment was marked as outdated.

Sign in to view

fix(subagent): resolve review conflicts and strengthen coverage

9384e80

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

xgopilot and others added 3 commits April 14, 2026 16:18

fix(runtime): resolve merge conflicts with main event/runtime changes

cc74bd4

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

fix(runtime): align runtime core with main to resolve merge conflicts

730a61b

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

refactor(runtime): decouple subagent factory storage from service struct

a5bf778

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

fennoai Bot mentioned this pull request Apr 14, 2026

NeoCode 运行时与能力分层优化计划（修订版） #272

Closed

This comment was marked as outdated.

Sign in to view

fix(subagent): resolve review issues for factory lifecycle and defaul…

e43f70c

…t output contract Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

xgopilot and others added 3 commits April 15, 2026 02:41

fix(runtime): resolve main merge conflicts for subagent runtime

062846d

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

refactor(runtime): align state model with main-compatible event envelope

631d8ab

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

test(runtime): align helper tests with main to remove merge conflicts

1afecba

Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

fennoai Bot reviewed Apr 15, 2026

View reviewed changes

xgopilot and others added 2 commits April 15, 2026 03:26

fix(subagent): address review gaps in progress envelope and capabilit…

727ed3f

…y bounds Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: Cai-Tang-www <106404101+Cai-Tang-www@users.noreply.github.com>

Merge branch 'main' into feat(subagent)

5202821

phantom5099 merged commit 5c44480 into 1024XEngineer:main Apr 15, 2026
2 checks passed

Uh oh!

Conversation

Cai-Tang-www commented Apr 14, 2026

背景

本次改动

1) 新增 internal/subagent 核心模块

2) Runtime 接入

3) 测试

设计边界

Uh oh!

codecov Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment was marked as outdated.

Uh oh!

Cai-Tang-www commented Apr 14, 2026

Uh oh!

fennoai Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

结果

已完成内容

提交信息

未执行项

Uh oh!

Cai-Tang-www commented Apr 14, 2026

Uh oh!

fennoai Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

处理结果

已完成内容

验证结果

提交与推送

未执行项

Uh oh!

wynxing commented Apr 15, 2026

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Cai-Tang-www commented Apr 15, 2026

Uh oh!

fennoai Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

处理结果

已完成项

验证

提交与推送

未执行项

Uh oh!

Cai-Tang-www commented Apr 15, 2026

Uh oh!

fennoai Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

处理结果

已完成内容

验证

提交与推送

未执行项

Uh oh!

phantom5099 commented Apr 15, 2026

Uh oh!

fennoai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

fennoai Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fennoai Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fennoai Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fennoai Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

1) 新增 `internal/subagent` 核心模块

codecov Bot commented Apr 14, 2026 •

edited

Loading

fennoai Bot commented Apr 14, 2026 •

edited

Loading

fennoai Bot commented Apr 14, 2026 •

edited

Loading

fennoai Bot commented Apr 15, 2026 •

edited

Loading

fennoai Bot commented Apr 15, 2026 •

edited

Loading

fennoai Bot commented Apr 15, 2026 •

edited

Loading